| 1 | /* $NetBSD: pipe.c,v 1.2 2017/02/14 01:16:46 christos Exp $ */ |
| 2 | |
| 3 | /*++ |
| 4 | /* NAME |
| 5 | /* pipe 8 |
| 6 | /* SUMMARY |
| 7 | /* Postfix delivery to external command |
| 8 | /* SYNOPSIS |
| 9 | /* \fBpipe\fR [generic Postfix daemon options] command_attributes... |
| 10 | /* DESCRIPTION |
| 11 | /* The \fBpipe\fR(8) daemon processes requests from the Postfix queue |
| 12 | /* manager to deliver messages to external commands. |
| 13 | /* This program expects to be run from the \fBmaster\fR(8) process |
| 14 | /* manager. |
| 15 | /* |
| 16 | /* Message attributes such as sender address, recipient address and |
| 17 | /* next-hop host name can be specified as command-line macros that are |
| 18 | /* expanded before the external command is executed. |
| 19 | /* |
| 20 | /* The \fBpipe\fR(8) daemon updates queue files and marks recipients |
| 21 | /* as finished, or it informs the queue manager that delivery should |
| 22 | /* be tried again at a later time. Delivery status reports are sent |
| 23 | /* to the \fBbounce\fR(8), \fBdefer\fR(8) or \fBtrace\fR(8) daemon as |
| 24 | /* appropriate. |
| 25 | /* SINGLE-RECIPIENT DELIVERY |
| 26 | /* .ad |
| 27 | /* .fi |
| 28 | /* Some destinations cannot handle more than one recipient per |
| 29 | /* delivery request. Examples are pagers or fax machines. |
| 30 | /* In addition, multi-recipient delivery is undesirable when |
| 31 | /* prepending a \fBDelivered-to:\fR or \fBX-Original-To:\fR |
| 32 | /* message header. |
| 33 | /* |
| 34 | /* To prevent Postfix from sending multiple recipients per delivery |
| 35 | /* request, specify |
| 36 | /* .sp |
| 37 | /* .nf |
| 38 | /* \fItransport\fB_destination_recipient_limit = 1\fR |
| 39 | /* .fi |
| 40 | /* |
| 41 | /* in the Postfix \fBmain.cf\fR file, where \fItransport\fR |
| 42 | /* is the name in the first column of the Postfix \fBmaster.cf\fR |
| 43 | /* entry for the pipe-based delivery transport. |
| 44 | /* COMMAND ATTRIBUTE SYNTAX |
| 45 | /* .ad |
| 46 | /* .fi |
| 47 | /* The external command attributes are given in the \fBmaster.cf\fR |
| 48 | /* file at the end of a service definition. The syntax is as follows: |
| 49 | /* .IP "\fBchroot=\fIpathname\fR (optional)" |
| 50 | /* Change the process root directory and working directory to |
| 51 | /* the named directory. This happens before switching to the |
| 52 | /* privileges specified with the \fBuser\fR attribute, and |
| 53 | /* before executing the optional \fBdirectory=\fIpathname\fR |
| 54 | /* directive. Delivery is deferred in case of failure. |
| 55 | /* .sp |
| 56 | /* This feature is available as of Postfix 2.3. |
| 57 | /* .IP "\fBdirectory=\fIpathname\fR (optional)" |
| 58 | /* Change to the named directory before executing the external command. |
| 59 | /* The directory must be accessible for the user specified with the |
| 60 | /* \fBuser\fR attribute (see below). |
| 61 | /* The default working directory is \fB$queue_directory\fR. |
| 62 | /* Delivery is deferred in case of failure. |
| 63 | /* .sp |
| 64 | /* This feature is available as of Postfix 2.2. |
| 65 | /* .IP "\fBeol=\fIstring\fR (optional, default: \fB\en\fR)" |
| 66 | /* The output record delimiter. Typically one would use either |
| 67 | /* \fB\er\en\fR or \fB\en\fR. The usual C-style backslash escape |
| 68 | /* sequences are recognized: \fB\ea \eb \ef \en \er \et \ev |
| 69 | /* \e\fIddd\fR (up to three octal digits) and \fB\e\e\fR. |
| 70 | /* .IP "\fBflags=BDFORXhqu.>\fR (optional)" |
| 71 | /* Optional message processing flags. By default, a message is |
| 72 | /* copied unchanged. |
| 73 | /* .RS |
| 74 | /* .IP \fBB\fR |
| 75 | /* Append a blank line at the end of each message. This is required |
| 76 | /* by some mail user agents that recognize "\fBFrom \fR" lines only |
| 77 | /* when preceded by a blank line. |
| 78 | /* .IP \fBD\fR |
| 79 | /* Prepend a "\fBDelivered-To: \fIrecipient\fR" message header with the |
| 80 | /* envelope recipient address. Note: for this to work, the |
| 81 | /* \fItransport\fB_destination_recipient_limit\fR must be 1 |
| 82 | /* (see SINGLE-RECIPIENT DELIVERY above for details). |
| 83 | /* .sp |
| 84 | /* The \fBD\fR flag also enforces loop detection (Postfix 2.5 and later): |
| 85 | /* if a message already contains a \fBDelivered-To:\fR header |
| 86 | /* with the same recipient address, then the message is |
| 87 | /* returned as undeliverable. The address comparison is case |
| 88 | /* insensitive. |
| 89 | /* .sp |
| 90 | /* This feature is available as of Postfix 2.0. |
| 91 | /* .IP \fBF\fR |
| 92 | /* Prepend a "\fBFrom \fIsender time_stamp\fR" envelope header to |
| 93 | /* the message content. |
| 94 | /* This is expected by, for example, \fBUUCP\fR software. |
| 95 | /* .IP \fBO\fR |
| 96 | /* Prepend an "\fBX-Original-To: \fIrecipient\fR" message header |
| 97 | /* with the recipient address as given to Postfix. Note: for this to |
| 98 | /* work, the \fItransport\fB_destination_recipient_limit\fR must be 1 |
| 99 | /* (see SINGLE-RECIPIENT DELIVERY above for details). |
| 100 | /* .sp |
| 101 | /* This feature is available as of Postfix 2.0. |
| 102 | /* .IP \fBR\fR |
| 103 | /* Prepend a \fBReturn-Path:\fR message header with the envelope sender |
| 104 | /* address. |
| 105 | /* .IP \fBX\fR |
| 106 | /* Indicate that the external command performs final delivery. |
| 107 | /* This flag affects the status reported in "success" DSN |
| 108 | /* (delivery status notification) messages, and changes it |
| 109 | /* from "relayed" into "delivered". |
| 110 | /* .sp |
| 111 | /* This feature is available as of Postfix 2.5. |
| 112 | /* .IP \fBh\fR |
| 113 | /* Fold the command-line \fB$original_recipient\fR and |
| 114 | /* \fB$recipient\fR address domain part |
| 115 | /* (text to the right of the right-most \fB@\fR character) to |
| 116 | /* lower case; fold the entire command-line \fB$domain\fR and |
| 117 | /* \fB$nexthop\fR host or domain information to lower case. |
| 118 | /* This is recommended for delivery via \fBUUCP\fR. |
| 119 | /* .IP \fBq\fR |
| 120 | /* Quote white space and other special characters in the command-line |
| 121 | /* \fB$sender\fR, \fB$original_recipient\fR and \fB$recipient\fR |
| 122 | /* address localparts (text to the |
| 123 | /* left of the right-most \fB@\fR character), according to an 8-bit |
| 124 | /* transparent version of RFC 822. |
| 125 | /* This is recommended for delivery via \fBUUCP\fR or \fBBSMTP\fR. |
| 126 | /* .sp |
| 127 | /* The result is compatible with the address parsing of command-line |
| 128 | /* recipients by the Postfix \fBsendmail\fR(1) mail submission command. |
| 129 | /* .sp |
| 130 | /* The \fBq\fR flag affects only entire addresses, not the partial |
| 131 | /* address information from the \fB$user\fR, \fB$extension\fR or |
| 132 | /* \fB$mailbox\fR command-line macros. |
| 133 | /* .IP \fBu\fR |
| 134 | /* Fold the command-line \fB$original_recipient\fR and |
| 135 | /* \fB$recipient\fR address localpart (text to |
| 136 | /* the left of the right-most \fB@\fR character) to lower case. |
| 137 | /* This is recommended for delivery via \fBUUCP\fR. |
| 138 | /* .IP \fB.\fR |
| 139 | /* Prepend "\fB.\fR" to lines starting with "\fB.\fR". This is needed |
| 140 | /* by, for example, \fBBSMTP\fR software. |
| 141 | /* .IP \fB>\fR |
| 142 | /* Prepend "\fB>\fR" to lines starting with "\fBFrom \fR". This is expected |
| 143 | /* by, for example, \fBUUCP\fR software. |
| 144 | /* .RE |
| 145 | /* .IP "\fBnull_sender\fR=\fIreplacement\fR (default: MAILER-DAEMON)" |
| 146 | /* Replace the null sender address (typically used for delivery |
| 147 | /* status notifications) with the specified text |
| 148 | /* when expanding the \fB$sender\fR command-line macro, and |
| 149 | /* when generating a From_ or Return-Path: message header. |
| 150 | /* |
| 151 | /* If the null sender replacement text is a non-empty string |
| 152 | /* then it is affected by the \fBq\fR flag for address quoting |
| 153 | /* in command-line arguments. |
| 154 | /* |
| 155 | /* The null sender replacement text may be empty; this form |
| 156 | /* is recommended for content filters that feed mail back into |
| 157 | /* Postfix. The empty sender address is not affected by the |
| 158 | /* \fBq\fR flag for address quoting in command-line arguments. |
| 159 | /* .sp |
| 160 | /* Caution: a null sender address is easily mis-parsed by |
| 161 | /* naive software. For example, when the \fBpipe\fR(8) daemon |
| 162 | /* executes a command such as: |
| 163 | /* .sp |
| 164 | /* .nf |
| 165 | /* \fIWrong\fR: command -f$sender -- $recipient |
| 166 | /* .fi |
| 167 | /* .IP |
| 168 | /* the command will mis-parse the -f option value when the |
| 169 | /* sender address is a null string. For correct parsing, |
| 170 | /* specify \fB$sender\fR as an argument by itself: |
| 171 | /* .sp |
| 172 | /* .nf |
| 173 | /* \fIRight\fR: command -f $sender -- $recipient |
| 174 | /* .fi |
| 175 | /* .IP |
| 176 | /* This feature is available as of Postfix 2.3. |
| 177 | /* .IP "\fBsize\fR=\fIsize_limit\fR (optional)" |
| 178 | /* Don't deliver messages that exceed this size limit (in |
| 179 | /* bytes); return them to the sender instead. |
| 180 | /* .IP "\fBuser\fR=\fIusername\fR (required)" |
| 181 | /* .IP "\fBuser\fR=\fIusername\fR:\fIgroupname\fR" |
| 182 | /* Execute the external command with the user ID and group ID of the |
| 183 | /* specified \fIusername\fR. The software refuses to execute |
| 184 | /* commands with root privileges, or with the privileges of the |
| 185 | /* mail system owner. If \fIgroupname\fR is specified, the |
| 186 | /* corresponding group ID is used instead of the group ID of |
| 187 | /* \fIusername\fR. |
| 188 | /* .IP "\fBargv\fR=\fIcommand\fR... (required)" |
| 189 | /* The command to be executed. This must be specified as the |
| 190 | /* last command attribute. |
| 191 | /* The command is executed directly, i.e. without interpretation of |
| 192 | /* shell meta characters by a shell command interpreter. |
| 193 | /* .sp |
| 194 | /* Specify "{" and "}" around command arguments that contain |
| 195 | /* whitespace (Postfix 3.0 and later). Whitespace |
| 196 | /* after "{" and before "}" is ignored. |
| 197 | /* .sp |
| 198 | /* In the command argument vector, the following macros are recognized |
| 199 | /* and replaced with corresponding information from the Postfix queue |
| 200 | /* manager delivery request. |
| 201 | /* .sp |
| 202 | /* In addition to the form ${\fIname\fR}, the forms $\fIname\fR and |
| 203 | /* the deprecated form $(\fIname\fR) are also recognized. |
| 204 | /* Specify \fB$$\fR where a single \fB$\fR is wanted. |
| 205 | /* .RS |
| 206 | /* .IP \fB${client_address}\fR |
| 207 | /* This macro expands to the remote client network address. |
| 208 | /* .sp |
| 209 | /* This feature is available as of Postfix 2.2. |
| 210 | /* .IP \fB${client_helo}\fR |
| 211 | /* This macro expands to the remote client HELO command parameter. |
| 212 | /* .sp |
| 213 | /* This feature is available as of Postfix 2.2. |
| 214 | /* .IP \fB${client_hostname}\fR |
| 215 | /* This macro expands to the remote client hostname. |
| 216 | /* .sp |
| 217 | /* This feature is available as of Postfix 2.2. |
| 218 | /* .IP \fB${client_port}\fR |
| 219 | /* This macro expands to the remote client TCP port number. |
| 220 | /* .sp |
| 221 | /* This feature is available as of Postfix 2.5. |
| 222 | /* .IP \fB${client_protocol}\fR |
| 223 | /* This macro expands to the remote client protocol. |
| 224 | /* .sp |
| 225 | /* This feature is available as of Postfix 2.2. |
| 226 | /* .IP \fB${domain}\fR |
| 227 | /* This macro expands to the domain portion of the recipient |
| 228 | /* address. For example, with an address \fIuser+foo@domain\fR |
| 229 | /* the domain is \fIdomain\fR. |
| 230 | /* .sp |
| 231 | /* This information is modified by the \fBh\fR flag for case folding. |
| 232 | /* .sp |
| 233 | /* This feature is available as of Postfix 2.5. |
| 234 | /* .IP \fB${extension}\fR |
| 235 | /* This macro expands to the extension part of a recipient address. |
| 236 | /* For example, with an address \fIuser+foo@domain\fR the extension is |
| 237 | /* \fIfoo\fR. |
| 238 | /* .sp |
| 239 | /* A command-line argument that contains \fB${extension}\fR expands |
| 240 | /* into as many command-line arguments as there are recipients. |
| 241 | /* .sp |
| 242 | /* This information is modified by the \fBu\fR flag for case folding. |
| 243 | /* .IP \fB${mailbox}\fR |
| 244 | /* This macro expands to the complete local part of a recipient address. |
| 245 | /* For example, with an address \fIuser+foo@domain\fR the mailbox is |
| 246 | /* \fIuser+foo\fR. |
| 247 | /* .sp |
| 248 | /* A command-line argument that contains \fB${mailbox}\fR |
| 249 | /* expands to as many command-line arguments as there are recipients. |
| 250 | /* .sp |
| 251 | /* This information is modified by the \fBu\fR flag for case folding. |
| 252 | /* .IP \fB${nexthop}\fR |
| 253 | /* This macro expands to the next-hop hostname. |
| 254 | |
|---|